\chapter{Hart to encoder interface} \label{Interface}

\section{Interface requirements}
This section describes in general terms the information which must be passed from the RISC-V hart to the trace encoder,
and distinguishes between what is mandatory, and what is optional.

The following information is mandatory:

\begin{itemize}
  \item The number of instructions that are being retired;
  \item Whether there has been an exception or interrupt, and if so the cause (from the \textbf{\textit{ucause/scause/mcause}} CSR)
        and trap value (from the \textbf{\textit{utval/stval/mtval}} CSR);
  \item The current privilege level of the RISC-V hart;
  \item The \textit{instruction\_type} of retired instructions for:
    \begin{itemize}
      \item Jumps with a target that cannot be inferred from the source code;
      \item Taken and nontaken branches;
      \item Return from exception or interrupt (\textbf{\textit{*ret}} instructions).
    \end{itemize}
  \item The \textit{instruction\_address} for:
    \begin{itemize}
      \item Jumps with a target that \textit{cannot} be inferred from the source code;
      \item The instruction retired immediately after a jump with a target that \textit{cannot} be inferred 
        from the source code (also referred to as the target or destination of the jump);
      \item Taken and nontaken branches;
      \item The last instruction retired before an exception or interrupt;
      \item The first instruction retired following an exception or interrupt;
      \item The last instruction retired before a privilege change;
      \item The first instruction retired following a privilege change.
    \end{itemize}
\end{itemize}

The following information is optional:

\begin{itemize}
  \item Context information:
    \begin{itemize}
      \item The context and/or hart ID;
      \item The type of action to take when context changes.
    \end{itemize}
  \item The \textit{instruction\_type} of instructions for:
    \begin{itemize}
      \item Calls with a target that \textit{cannot} be inferred from the source code;
      \item Calls with a target that \textit{can} be inferred from the source code;
      \item Tail-calls with a target that \textit{cannot} be inferred from the source code;
      \item Tail-calls with a target that \textit{can} be inferred from the source code;
      \item Returns with a target that \textit{cannot} be inferred from the source code;
      \item Returns with a target that \textit{can} be inferred from the source code;
      \item Co-routine swap;
      \item Jumps which don't fit any of the above classifications with a target that \textit{cannot} be inferred from the source code;
      \item Jumps which don't fit any of the above classifications with a target that \textit{can} be inferred from the source code.
    \end{itemize}
  \item If context is supported then the \textit{instruction\_address} for:
    \begin{itemize}
      \item The last instruction retired before a context change;
      \item The first instruction retired following a context change.
    \end{itemize}
  \item Whether jump targets are sequentially inferable or not.
\end{itemize}

The mandatory information is the bare-minimum required to implement the branch trace algorithm outlined in Chapter~\ref{Algorithm}.  
The optional information facilitates alternative or improved trace algorithms:

\begin{itemize}
  \item Implicit return mode (see Section~\ref{sec:implicit-return}) requires the encoder to keep track of the number of nested 
    function calls, and to do this it must be aware of all calls and returns regardless of whether the target can be inferred or not;
  \item A simpler algorithm useful for basic code profiling would only report function calls and returns, again 
    regardless of whether the target can be inferred or not;
  \item Branch prediction techniques can be used to further improve the encoder efficiency, particularly for loops 
    (see Section~\ref{sec:branch-prediction}).  This requires the encoder to be aware of the address of all branches, whether
    they are taken or not.
  \item Uninferable jumps can be treated as inferable (which don't need to be reported in the trace output) if both the jump 
    and the preceding instruction which loads the target into a register have been traced.
\end{itemize}

\subsection{Jump classification and target inference} \label{Jump Classes}

Jumps are classified as \textit{inferable}, or \textit{uninferable}.  An \textit{inferable} jump has a target which can be
deduced from the binary executable or representation thereof (e.g. ELF).  For the purposes of this specification, the following 
strict definition applies:

If the target of a jump is supplied via a constant embedded within the jump opcode, it is classified as \textit{inferable}.
Jumps which are not \textit{inferable} are by definition \textit{uninferable}.

However, there are some jump targets which can still be deduced from the binary executable by considering pairs of instructions
even though by the above definition they are classified as uninferable.  Specifically, jump targets that are supplied via

\begin{itemize}
  \item an \textbf{\textit{lui}} or \textbf{\textit{c.lui}} (a register which contains a constant), or
  \item an \textbf{\textit{auipc}} (a register which contains a constant offset from the PC).
\end{itemize}

Such jump targets are classified as \textit{sequentially inferable} if the pair of instructions are retired consecutively 
(i.e. the \textbf{\textit{auipc}}, \textbf{\textit{lui}} or \textbf{\textit{c.lui}} immediately precedes the jump).  Note:
the restriction that the instructions are retired consecutively is necessary in order to minimize the additional signalling
needed between the hart and the encoder, and should have a minimal impact on trace efficiency as it is anticipated that
consecutive execution will be the norm. Support for sequentially inferable jumps is optional.

Jumps may optionally be further classified according to the recommended calling convention:

\begin{itemize}
  \item \textit{Calls}: 
    \begin{itemize}
      \item \textbf{\textit{jal}} x1;
      \item \textbf{\textit{jal}} x5;
      \item \textbf{\textit{jalr}} x1, rs  where rs != x1;
      \item \textbf{\textit{jalr}} x5, rs  where rs != x5;
      \item \textbf{\textit{c.jalr}} rs1.
    \end{itemize}
  \item \textit{Tail-calls}: 
    \begin{itemize}
      \item \textbf{\textit{jalr}} x0, rs where rs != x1 and rs != x5;
      \item \textbf{\textit{c.jr}} rs1 where rs1 != x1 and rs1 != x5.
    \end{itemize}
  \item \textit{Returns}: 
    \begin{itemize}
      \item \textbf{\textit{jalr}} x0, rs where rs == x1 or rs == x5;
      \item \textbf{\textit{c.jr}} rs1 where rs1 == x1 or rs1 == x5.
    \end{itemize}
  \item \textit{Co-routine swap}: 
    \begin{itemize}
      \item \textbf{\textit{jalr}} x1, x1;
      \item \textbf{\textit{jalr}} x5, x5.
    \end{itemize}
  \item \textit{Other}: 
    \begin{itemize}
      \item \textbf{\textit{jal}} rd where rd != x1 and rd != x5;
      \item \textbf{\textit{jalr}} rd, rs where rd != x0 and rd != x1 and rd != x5.
    \end{itemize}
\end{itemize}

\subsection{Relationship betweem RISC-V core and the encoder} \label{sec:relationship}

The encoder is intended to encode the instructions executed on a single hart.  

It is however commonplace for a RISC-V core to contain multiple harts.  This can be 
supported by the core in several different ways:

\begin{itemize}
  \item Implement a separate instance of the interface per hart.  Each instance can be connected
    to a separate encoder instance, allowing all harts to be traced concurrently.  Alternatively,
    external muxing may be used in conjunction with a single encoder in order to trace one particular 
    hart at a time;
  \item Implement a singe interface for the core, with muxing inside the core to select which hart to 
  connect to the interface.
\end{itemize}

(Whilst it is technically feasible to use a single encoder with multiple harts operating 
in a fine-grained multi-threaded configuration, the frequent context changes that would occur
as a result of thread-switching would result in extremely poor encoding efficiency, and so
this configuration is not recommended.)

\section{Instruction interface}
This section describes the interface between a RISC-V hart and the
trace encoder that conveys the information described in the previous section.  
Signals are assigned to one of the  following groups:

\begin{itemize}
  \item M: Mandatory.  The interface must include an instance of this signal.
  \item O: Optional.  The interface may include an instance of this signal.
  \item MR: Mandatory, may be replicated. For harts that can retire a maximum of N taken branches per clock
    cycle, the interface must include N instances of this signal.
  \item OR: Optional, may be replicated. For harts that can retire a maximum of N taken branches per clock
    cycle, the interface must include zero or N instances of this signal.
  \item BR: Block, may be replicated.  Mandatory for harts that can retire multiple instructions in a block.  
    Replication as per OR.  If omitted, the interface must include SR group signals instead.
  \item SR: Single, may be replicated.  Mandatory for harts that can only retire one instruction in a block.  
    Replication as per OR (see section~\ref{sec:alt-multi}).  If omitted, the interface must include BR 
    group signals instead.
\end{itemize}

\begin{table}[htp]
    \centering
    \caption{Instruction interface signals}
    \label{tab:common-ingress}
    \begin{tabulary}{\textwidth}{|l|l|p{80mm}|}
        \hline
        \textbf{Signal} & \textbf{Group} & \textbf{Function} \\
        \hline
        \textbf{itype}[\textit{itype\_width\_p}-1:0] & MR & Termination type of the instruction block (see Section~\ref{Jump Classes} for definitions of codes 6 - 15):\newline
        0: Final instruction in the block is none of the other named \textbf{itype} codes;\newline
        1: Exception. An exception that traps occurred following the final retired instruction in the block;\newline
        2: Interrupt. An interrupt that traps occurred following the final retired instruction in the block;\newline
        3: Exception or interrupt return;\newline
        4: Nontaken branch;\newline
        5: Taken branch;\newline
        6: reserved;\newline
        7: Co-routine swap;\newline
        8: Uninferable call;\newline
        9: Inferrable call;\newline
        10: Uninferable tail-call;\newline
        11: Inferrable tail-call;\newline
        12: Uninferable return;\newline
        13: Inferrable return;\newline
        14: Other uninferable jump;\newline
        15: Other inferable jump.\\
        \hline
        \textbf{cause}[\textit{ecause\_width\_p}-1:0] & M & Exception or interrupt cause (\textbf{\textit{ucause/scause/ mcause}}).
        Ignored unless \textbf {itype}=1 or 2.\\
        \hline
        \textbf{tval}[\textit{iaddress\_width\_p}-1:0] & M & The associated trap value, e.g. the
        faulting virtual address for address exceptions, as would be
        written to the \textbf{utval/stval/mtval} CSR. Future optional extensions may define \textbf{tval} 
        to provide ancillary information in cases where it currently supplies zero.
        Ignored unless \textbf{itype}=1 or 2.\\
        \hline
        \textbf{priv}[\textit{privilege\_width\_p}-1:0] & M & Privilege level for all instructions retired on this cycle.\\
        \hline
        \textbf{iaddr}[\textit{iaddress\_width\_p}-1:0] & MR & The address of the 1st instruction retired in this block.
        Invalid if \textbf{iretire}=0 \\
        \hline
        \textbf{context}[\textit{context\_width\_p}-1:0] & O & Context for all instructions retired on this cycle.\\
        \hline
        \textbf{ctype}[\textit{ctype\_width\_p}-1:0] & O & Reporting behavior for \textbf{context}:\newline
        0: Don't report; \newline
        1: Report imprecisely;\newline
        2: Report precisely;\newline
        3: Report as asynchronous discontinuity.\\
        \hline
        \textbf{sijump} & OR & If \textbf{itype} indicates that this block ends with an uninferable discontinuity, setting this signal to 1 
        indicates that it is sequentially inferable and may be treated as inferable by the encoder if the preceding 
        \textbf{\textit{auipc}}, \textbf{\textit{lui}} or \textbf{\textit{c.lui}} has been traced.  
        Ignored for \textbf{itype} codes other than 8, 10, 12 or 14.\\
        \hline
    \end{tabulary}
\end{table}

\begin{table}[htp]
    \centering
    \caption{Instruction interface signals - multiple retirement per block}
    \label{tab:multi-ingress}
    \begin{tabulary}{\textwidth}{|l|l|p{80mm}|}
        \hline
        \textbf{Signal} & \textbf{Group} & \textbf{Function} \\
        \hline
        \textbf{iretire}[\textit{iretire\_width\_p}-1:0] & BR & Number of halfwords represented by instructions retired in this block.\\
        \hline
        \textbf{ilastsize}[\textit{ilastsize\_width\_p}-1:0] & BR & The size of the last retired instruction is 2\textsuperscript{\textbf{ilastsize}} half-words.\\
        \hline
    \end{tabulary}
\end{table}

\begin{table}[htp]
    \centering
    \caption{Instruction interface signals - single retirement per block}
    \label{tab:single-ingress}
    \begin{tabulary}{\textwidth}{|l|l|p{110mm}|}
        \hline
        \textbf{Signal} & \textbf{Group} & \textbf{Function} \\
        \hline
        \textbf{iretire}[0:0] & SR & Number of instructions retired in this block (0 or 1).\\
        \hline
    \end{tabulary}
\end{table}

Tables~\ref{tab:common-ingress} and ~\ref{tab:multi-ingress}
list the signals in the interface designed to efficiently support retirement of multiple 
instructions per cycle.  The following discussion describes the multiple-retirement behavior.  
However, for harts that can only retire one instruction at a time, the signalling can be 
simplified, and this is discussed subsequently in Section~\ref{sec:single-retire}.  

The information presented in a block represents a contiguous
block of instructions starting at \textbf{iaddr}, all of which retired
in the same cycle. Note if \textbf{itype} is 1 or 2 (indicating an
exception or an interrupt), the number of instructions retired may be
zero. \textbf{cause} and \textbf{tval} are only defined if
\textbf{itype} is 1 or 2. If \textbf{iretire}=0 and \textbf{itype}=0,
the values of all other signals are undefined.

\textbf{iretire} contains the number of half-words represented by
instructions retired in this block, and \textbf{ilastsize} the size of the last
instruction.  Half-words rather than instruction count enables the encoder to easily compute the address of
the last instruction in the block without having access to the size of every 
instruction in the block.  

Whilst \textbf{iaddr} is typically a virtual address, it does not affect the encoder's behavior
if it is a phyical address.

For harts that can retire a maximum of N branches per clock
cycle, the signal groups MR, OR and either BR or SR must be replicated N times. 
Signal group 0 represents information about the oldest instruction block, and group N-1
represents the newest instruction block. The interface supports no more
than one privilege, context, exception or interrupt per cycle and so signals in
groups M and O are not replicated. Furthermore, \textbf{itype} can only
take the value 1 or 2 in one of the signal groups, and this must be
the newest valid group (i.e. \textbf{iretire} and \textbf{itype} must
be zero for higher numbered groups). If fewer than N branches
are retired in a cycle, then lower numbered groups must be used
first. For example, if there is one branch, use only group 0, if
there are two branches, instructions up to the 1st branch
must be reported in group 0 and instructions up to the 2nd branch
must be reported in group 1 and so on.

\textbf{sijump} is optional and may be omitted if the hart does not implement the logic to detect
sequentially inferable jumps.  If the encoder offers an \textbf{sijump} input it must also provide a
parameter to indicate whether the input is connected to a hart that implements this capability, or
tied off.  This is to ensure the decoder can be made aware of the hart's capability.  Enabling 
sequentially inferable jump mode in the encoder and decoder when the hart does not support it will
prevent correct reconstruction by the decoder. 

The \textbf{context} field can be used to convey any additional information to the decoder.  For example:

\begin{itemize}
  \item The software thread ID;
  \item The process ID from an operating system;
  \item It could be used to convey the values of CSRs to the decoder by setting \textbf{context} to the 
    CSR number and value when a CSR is written;
  \item In cases where a single encoder is being shared amongst multiple harts 
  (see section~\ref{sec:relationship}), it could also be used to indicate the hart ID, in cases where the 
  hart ID can be changed dynamically.
\end{itemize}

Table~\ref{tab:context-type} specifies the actions for the various \textbf{ctype} values.  A typical 
behaviour would be for this signal to remain zero except on the 1st retirement after a context change.

\begin{table}[htp]
    \centering
    \caption{Context type \textbf{ctype} values and corresponding actions}
    \label{tab:context-type}
    \begin{tabulary}{\textwidth}{|l|l|p{90mm}|}
        \hline
        \textbf{Type} & \textbf{Value} & \textbf{Actions} \\
        \hline
        Unreported & 0 & No action (don't report context).\\
        \hline
        Report context imprecisely & 1 & An example would be a SW thread or operating system process change.\newline
        Report the new context value at the earliest convenient opportunity.\newline
        It is reported without any address information, and the assumption is that the precise 
        point of context change can be deduced from the source code (e.g. a CSR write). \\
        \hline
        Report context precisely  & 2 & Report the address of the 1st instruction retired in this block, and the new context.\newline
        If there were unreported branches beforehand, these need to be reported first.\newline
        Treated the same as a privilege change.\\
        \hline
        Report context as an & 3 &  An example would be a change of hart.\\
        asynchronous discontinuity & & 
        Need to report the last instruction retired on the previous context, as well as the 1st on the new context.\newline
        Treated the same as an exception.\\
        \hline
    \end{tabulary}
\end{table}

\subsection{Simplifications for single-retirement} \label{sec:single-retire}

For harts that can only retire one instruction at a time, the interface can be simplified to
the signals listed in tables~\ref{tab:common-ingress} and ~\ref{tab:single-ingress}.  The 
simplifications can be summarized as follows:
 
\begin{itemize}
  \item As the number of instructions that are retired in a block is only 0 or 1, the 
    encoder does not need information to enable it to deduce the address of the last instruction 
    retired (it is the same as the 1st and only instruction retired).  So 
    \textbf{ilastsize} is not necessary, and \textbf{iretire} simply indicates whether an
    instruction retired or not.
\end{itemize}

The parameter \textit{retires\_p} which indicates to the encoder the maximum number of 
instructions that can be retired per cycle can be used by an encoder capable of supporting single or 
multiple retirement to select the appropriate interpretation of \textbf{iretire}.  
The \textbf{ilastsize} encoder input must be tied low when attached to a single-retirement
hart that does not provide these outputs.


\subsection{Alternative multiple-retirement interface configurations} \label{sec:alt-multi}

For a hart that can retire multiple instructions per cycle, but no more than one branch, the preferred 
solution is to use one instance of signals from groups BR, MR and OR.  However, if the hart can retire 
N branches in a cycle, N instances of signals from groups MR, OR and either SR or BR must be used 
(each instance can be either a single instruction or a block).

If the hart can retire N instructions per cycle, but only one branch, it is allowed (though not recommmended)
to provide explicit details of every instruction retired by using N instances of signals from groups
SR, MR and OR.

\subsection{Optional sideband signals}

Optional sideband signals may be included to provide additional functionality, as described in
tables \ref{tab:ingress-side-band} and \ref{tab:egress-side-band}.

Note, any user defined information that needs to be output by the encoder
will need to be applied via the \textbf{context} input.

\begin{table}[htp]
    \centering
    \caption{Optional sideband encoder input signals}
    \label{tab:ingress-side-band}
    \begin{tabulary}{\textwidth}{|l|l|p{90mm}|}
        \hline
        \textbf{Signal} & \textbf{Group} & \textbf{Function} \\
        \hline
        \textbf{impdef}[\textit{impdef\_width\_p}-1:0] & O &  Implementation defined sideband signals.  A typical use for
        these would be for filtering (see Chapter~\ref{ch:filtering}.\\
        \hline
        \textbf{trigger}[2:0] & OR & A pulse on bit 0 will cause the encoder to start tracing, and continue until further 
        notice, subject to other filtering criteria also being met.\newline
        A pulse on bit 1 will cause the encoder to stop tracing until further notice.  See section~\ref{sec:trigger}).\\
        \hline
        \textbf{halted} & O & Hart is halted.  Upon assertion, the encoder will output a packet to report the address 
        of the last instruction retired before halting, followed by a support packet to indicate that tracing has stopped. 
        Upon deassertion, the encoder will start tracing again, commencing with a synchronization packet.\\
        \hline
        \textbf{reset} & O & Hart is in reset.  Provided the encoder is in a different reset domain to the hart, this
        allows the encoder to indicate that tracing has ended on entry to reset, and restarted on exit.  
        Behavior is as described above for halt.\\
        \hline
    \end{tabulary}
\end{table}

\begin{table}[htp]
    \centering
    \caption{Optional sideband encoder output signals}
    \label{tab:egress-side-band}
    \begin{tabulary}{\textwidth}{|l|l|p{130mm}|}
        \hline
        \textbf{Signal} & \textbf{Group} & \textbf{Function} \\
        \hline
        \textbf{stall} & O & Stall request to hart.  Some applications may require lossless trace, which can be achieved by
        using this signal to stall the hart if the trace encoder is unable to output a trace packet (for example due to 
        back-pressure from the packet transport infrastructure).\\
        \hline
    \end{tabulary}
\end{table}

\FloatBarrier
\subsection{Using trigger outputs from the Debug Module} \label{sec:trigger}

The debug module of the RISC-V hart may have a trigger unit. This defines a match control register
(\textbf{\textit{mcontrol}}) containing a 4-bit \textbf{action} field, and reserves codes 2 - 5 
of this field for trace use.  
These action codes are hereby defined as shown in table \ref{tab:debugModuleTriggerSupport}.
If implemented, each action must generate a pulse on an output from the hart, on the same cycle as the instruction which
caused the trigger is retired.  

\begin{table}[!h]
    \centering
    \caption{Debug Module trigger support (\textbf{\textit{mcontrol}} \textbf{action})}
    \label{tab:debugModuleTriggerSupport}
    \begin{tabulary}{\textwidth}{|l|p{120mm}|}
        \hline
        \textbf {Value} & \textbf {Description} \\
        \hline
        2 & \textit{Trace-on}.  This should be connected to 
        \textbf{trigger[0]} if the encoder provides it. \\ 
        \hline
        3 & \textit{Trace-off}.  This should be connected to 
        \textbf{trigger[1]} if the encoder provides it. \\
        \hline
        4 & \textit{Trace-notify}.  This should be connected to 
        \textbf{trigger[2]} if the encoder provides it. This will cause the encoder to output
        a packet containing the address of the last instruction in the block if it is enabled.\\
        \hline
    \end{tabulary}
\end{table}

Trace-on and Trace-off actions provide a means for the hart to control when tracing occurs.  
Trace-notify provides  means to ensure that a specified instruction is explicitly reported.  
This capability is sometimes known as a watchpoint.

\FloatBarrier
\subsection{Example retirement sequences}

\begin{table}[htp]
    \centering
    \caption{Example 1 : 9 Instructions retired over four cycles, 2 branches} 
    \label{tab:signal-block-9-instructions-2-branches}
    \begin{tabulary}{\textwidth}{|l|l|}
        \hline
        \textbf {Retired} & \textbf {Instruction Trace Block} \\
        \hline
        1000: \textbf{\textit{divuw}} &  \textbf{iretire}=7, \textbf{iaddr}=0x1000, \textbf{itype}=8\\
        1004: \textbf{\textit{add}} &  \\
        1008: \textbf{\textit{or}} &  \\
        100C: \textbf{\textit{c.jalr}} &  \\
        \hline
        0940: \textbf{\textit{addi}} &  \textbf{iretire}=3, \textbf{iaddr}=0x0940, \textbf{itype}=4\\
        0944: \textbf{\textit{c.beq}} &  \\
        \hline
        0946: \textbf{\textit{c.bnez}} &  \textbf{iretire}=1, \textbf{iaddr}=0x0946, \textbf{itype}=5\\
        \hline
        0988: \textbf{\textit{lbu}} &  \textbf{iretire}=4, \textbf{iaddr}=0x0988, \textbf{itype}=0\\
        098C: \textbf{\textit{csrrw}} &  \\
        \hline
    \end{tabulary}
\end{table}

